NAZWA¶

mbtowc - przekształca ciąg wielobajtowy na znak szeroki

SKŁADNIA¶

#include <stdlib.h>

int mbtowc(wchar_t *pwc, const char *s, size_t n);

OPIS¶

Podstawową dla tej funkcji jest sytuacja gdy s jest różne od NULL i pwc jest różne od NULL. W tym przypadku, funkcja mbtowc sprawdza co najwyżej n bajtów ciągu wielobajtowego, zaczynając od s, wydziela następny pełny znak wielobajtowy, przetwarza go na znak szeroki i umieszcza w *pwc. Aktualizuje ona wewnętrzny, znany tylko funkcji mbtowc, stan przesunięty. Jeśli s nie wskazuje na bajt '\0', funkcja zwraca liczbę bajtów s, które zostały zużyte; w pozostałych przypadkach zwracane jest 0.

Jeśli n bajtów, poczynając od s nie zawiera pełnego znaku wielobajtowego, lub jeśli zawierają one niepoprawny ciąg wielobajtowy, mbtowc zwraca -1. Może się to zdarzyć nawet gdy n >= MB_CUR_MAX, jeśli wielobajtowy łańcuch zawiera nadmiarowe ciągi przesunięć.

Inna sytuacja ma miejsce, gdy s jest różne od NULL, ale pwc jest równe NULL. Wówczas funkcja mbtowc zachowuje się jak powyżej, z tym wyjątkiem, że nie przechowuje przetworzonego znaku szerokiego w pamięci.

Trzecia sytuacja występuje, gdy s jest równe NULL. Wówczas pwc i n są ignorowane. Funkcja mbtowc sprowadza stan przesunięty, znany tylko tej funkcji, do stanu wyjściowego i zwraca wartość różną od zera gdy kodowanie posiada nietrywialne stany przesunięte, a zero jeśli kodowanie jest bezstanowe.

WARTOŚĆ ZWRACANA¶

Jeśli s jest różne od NULL, funkcja mbtowc zwraca liczbę zużytych bajtów, poczynając od s, a 0 jeśli s wskazuje na bajt null, lub -1 w przypadku błędu.

Jeśli s jest równe NULL, funkcja mbtowc zwraca wartość różną od zera gdy kodowanie posiada nietrywialne stany przesunięte, a zero gdy kodowanie jest bezstanowe.

ZGODNE Z¶

ISO/ANSI C, UNIX98

ZOBACZ TAKŻE¶

mbrtowc(3), mbstowcs(3), MB_CUR_MAX(3)

UWAGI¶

Zachowanie mbtowc zależy od kategorii LC_CTYPE bieżącego locale.

Funkcja ta nie jest przystosowana do wielowątkowości. Funkcja mbrtowc zapewnia lepszy interfejs przy tym samym działaniu.